﻿//-----------------------------------------------------------------------------------------
// <copyright file="Led.cs" company="Jakub Florczyk (www.jakubflorczyk.pl)">
//      Copyright © 2009 Jakub Florczyk (www.jakubflorczyk.pl)
//      http://samsungmobilesdknet.codeplex.com
// </copyright>
//-----------------------------------------------------------------------------------------

namespace SamsungMobileSDKNET
{
    using System;
    using System.Runtime.InteropServices;

    /// <summary>
    /// LED ID definition.
    /// </summary>
    public enum LedID : uint
    {
        /// <summary>
        /// The ID for the notification LED.
        /// </summary>
        Notification = 0,

        /// <summary>
        /// The ID for the keypad LED.
        /// </summary>
        Keypad = 1
    }

    /// <summary>
    /// LED error codes.
    /// </summary>
    public enum LedError
    {
        /// <summary>
        /// Color unsupported.
        /// </summary>
        ColorUnsupported = ResultCode.LedResultBase
    }

    /// <summary>
    /// LED lighting patterns.
    /// </summary>
    public enum LedPattern
    {
        /// <summary>
        /// Solid pattern.
        /// </summary>
        Solid,

        /// <summary>
        /// Blinking pattern.
        /// </summary>
        Blinking
    }

    /// <summary>
    /// Led colors.
    /// </summary>
    public enum LedColor : uint
    {
        /// <summary>
        /// Red color.
        /// </summary>
        Red = 0x000000FF,

        /// <summary>
        /// Green color.
        /// </summary>
        Green = 0x0000FF00,

        /// <summary>
        /// Yellow color.
        /// </summary>
        Yellow = 0x0000FFFF,

        /// <summary>
        /// Blue color.
        /// </summary>
        Blue = 0x00FF0000,

        /// <summary>
        /// Magenta color.
        /// </summary>
        Magenta = 0x00FF00FF,

        /// <summary>
        /// Cyan color.
        /// </summary>
        Cyan = 0x00FFFF00,

        /// <summary>
        /// White color.
        /// </summary>
        White = 0x00FFFFFF
    }

    /// <summary>
    /// Describes the light pattern of an LED.
    /// </summary>
    [StructLayout(LayoutKind.Sequential)]
    public struct LedAttributes
    {
        /// <summary>
        /// Indicates light pattern. 
        /// </summary>
        public LedPattern Pattern;

        /// <summary>
        /// The amount of time an LED is on in a single cycle, in milliseconds. 
        /// </summary>
        public uint OnTime;

        /// <summary>
        /// The amount of time an LED is off in a single cycle, in milliseconds. 
        /// </summary>
        public uint OffTime;

        /// <summary>
        /// The total play time for the LED, in milliseconds. The LED cycle (which is the on time plus the off time, in milliseconds) will be repeated for the duration. <see cref="F:SamsungMobileSDKNET.Led.InfiniteDuration"/> indicates an infinitely long LED on duration.
        /// <br/>
        /// In the case that on time plus off time is set greater than the duration, the duration is changed to the sum of the on time and off time.
        /// </summary>
        public uint Duration;

        /// <summary>
        /// The LED's color. The accuracy of the display of a color is dependent on the color intensity.  For example, with a color intensity of 1, any value from 0x000000 to 0x00007F is no color; any value from 0x000080 to <see cref="F:SamsungMobileSDKNET.Led.Color.Red"/> (0x0000FF) is a red color.
        /// </summary>
        public uint Color;
    }

    /// <summary>
    /// The capabilities of the LED.
    /// </summary>
    [StructLayout(LayoutKind.Sequential)]
    public struct LedCapabilities
    {
        /// <summary>
        /// LED blink support. Supports blink if value is TRUE, otherwise is FALSE.
        /// </summary>
        public bool BlinkIsSupported;

        /// <summary>
        /// Indicates the supported color intensity on the LED.
        /// </summary>
        /// <remarks>
        /// A colorIntensity value of 1 means R, G, B can each be either 0 or 1, yielding a total of 8 colors when used in combination.
        /// <br/>
        /// A color intensity value of 3 means R, G, B can each be either 0, 1, 2, or 3, yielding a total of 64 colors.
        /// </remarks>
        public uint ColorIntensity;

        /// <summary>
        /// The value indicates the maximum on time value allowed, or 0 if it is not adjustable.
        /// </summary>
        public uint MaxOnTime;

        /// <summary>
        /// The value indicates the maximum off time value allowed, or 0 if it is not adjustable.
        /// </summary>
        public uint MaxOffTime;

        /// <summary>
        /// The value indicates the maximum duration allowed, or 0 if it is not adjustable.
        /// </summary>
        public uint MaxDuration;
    }

    /// <summary>
    /// Samsung LED API.
    /// </summary>
    /// <remarks>
    /// A typical Samsung device contains two LEDs: a notification LED and a keyboard LED, both of which can be controlled with the LED API. (There is also an LCD display backlight, which is controlled by the settings interface and not the SMI LED API.)
    /// <br/><br/>
    /// The LED API controls two LED attributes:
    /// <list type="bullet">
    /// <item>Display State - The keyboard LED can be either on or off; the notification LED can be on, off, or blinking.</item>
    /// <item>Color - The notification LED can display different colors, depending on the hardware setting. The Keyboard LED is monochrome white.</item>
    /// </list>
    /// </remarks>
    public class Led
    {
        /// <summary>
        /// Infinitely long duration.
        /// </summary>
        public const uint InfiniteDuration = 0xFFFFFFFF;

        /// <summary>
        /// Gets the LED's capabilities information.
        /// </summary>
        /// <param name="id">The LED that will have its capabilities returned.</param>
        /// <param name="capabilities">A pointer to the LED capability info.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the capabilities parameter is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if an LED with that id is not supported by the SDK
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiLedGetCapabilities")]
        public static extern ResultCode GetCapabilities(
            [In] uint id,
            [Out] out LedCapabilities capabilities);

        /// <summary>
        /// Turns on an LED.
        /// </summary>
        /// <param name="id">The particular LED to be turned on.</param>
        /// <param name="attributes">The attributes of the designated LED device.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if one or more parameters is invalid
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if an LED with that id is not supported by the SDK
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.LedError.ColorUnsupported"/> if the color is not supported (used for notification LED only)
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        /// <remarks>
        /// Only notification LEDs support multiple colors.
        /// </remarks>
        [DllImport(Common.DllName, EntryPoint = "SmiLedTurnOn")]
        public static extern ResultCode TurnOn(
            [In] uint id,
            [In] LedAttributes[] attributes); 

        /// <summary>
        /// Turns off an LED.
        /// </summary>
        /// <param name="id">The particular LED to be turned off.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the id parameter is invalid
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if an LED with that id is not supported by the SDK 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiLedTurnOff")]
        public static extern ResultCode TurnOff(
            [In] uint id);

        /// <summary>
        /// Gets the number of available LEDs.
        /// </summary>
        /// <param name="ledCount">The number of LEDs.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if the input parameter is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if LEDs are not supported by the SDK on this phone model
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiLedGetCount")]
        public static extern ResultCode GetCount(
            [Out] out uint ledCount);        
    }
}
